﻿//-----------------------------------------------------------------------
// <copyright file="ITupleRelation.cs" company="tuliprules.org">
//     Copyright (c) 2010 tuplelister, tuliprules.org.
// </copyright>
// <summary>This is the ITupleRelation interface.</summary>
//-----------------------------------------------------------------------

namespace Tulip.Engine.Tuples
{
    using System;
    using System.Collections;
    using System.Collections.Generic;

    /// <summary>
    /// Interface.   Represents a Tuple Relation in a non-generic fashion.
    /// </summary>
    public interface ITupleRelation
    {
        /// <summary>
        /// Gets the index of the tuple relation.
        /// </summary>
        int Id { get; }

        /// <summary>
        /// Clears all tuples from the tuple relation.
        /// </summary>
        void ClearAllTuples();

        /// <summary>
        /// Adds a tuple to a tuple relation using all registered evaluators to select the
        /// tuple lists and append the tuple list to them.
        /// </summary>
        /// <param name="tuple">The tuple to be added to the tuple view.</param>
        void AddTuple(Tuple tuple);

        /// <summary>
        /// Processes a tuple and adds or amends a quantative tuple in a tuple relation using 
        /// all registered evaluators to select the tuple lists and append the tuple list to them.   
        /// If the addAll flag is true, the tuple is also added to a special list containing all 
        /// bindings of this type.
        /// </summary>
        /// <param name="tuple">The tuple to be processed.</param>
        /// <param name="quantificationTupleType">Type of quantification tuple to which this tuple will be map.</param>
        /// <returns>Boolean value indicating if the tuple should be re-asserted.</returns>
        bool AddTuple(Tuple tuple, Type quantificationTupleType);

        /// <summary>
        /// Removes a tuple from a tuple view.
        /// </summary>
        /// <param name="tuple">The tuple to be added to the tuple view.</param>
        void RemoveTuple(Tuple tuple);
    }

#pragma warning disable 1587
    /// <summary>
    /// Interface.   Represents a Tuple Relation is a generic fashion.
    /// </summary>
    /// <typeparam name="TTuple">The tuple type that will be stored in the tuple relation.</typeparam>
#if MONO201_COMPLIANT
    public interface ITupleRelation<TTuple> : ITupleRelation
#else
    public interface ITupleRelation<TTuple> : ITupleRelation where TTuple : Tuple
#endif
#pragma warning restore 1587
    {
        /// <summary>
        /// Returns a Tuple View from the group.
        /// </summary>
        /// <typeparam name="TKey">The view's key type.</typeparam>
        /// <param name="tupleIndexer">The tuple indexer used to select the view.</param>
        /// <returns>
        /// A tuple view consisting of a sorted list of lists of tuples.   The tuple view is 
        /// sorted by values returned from the delegate.
        /// </returns>
        /// <remarks>
        /// A Tuple View is a sorted list of lists of tuples.   All tuples are of a given type.
        /// The lists of tuples are sorted by values returned by a Tuple View evaluator.    The 
        /// evaluator is used as the key value for tuple views in order to store and retrieve them
        /// from the tuple relation. 
        /// </remarks>
        Dictionary<TKey, TupleLinkedList> GetTupleView<TKey>(TupleIndexer<TTuple> tupleIndexer);

        /// <summary>
        /// Returns a Tuple View from the group for all tuples.
        /// </summary>
        /// <typeparam name="TKey">The key type.</typeparam>
        /// <returns>
        /// A tuple view consisting of a sorted list of lists of tuples.   The tuple view list
        /// contains a single list containing all tuples.
        /// </returns>
        /// <remarks>
        /// A Tuple View is a sorted list of lists of tuples.   All tuples are of a given type.
        /// In this case, the inner list contains all tuples of the given type.
        /// </remarks>
        Dictionary<TKey, TupleLinkedList> GetTupleView<TKey>();

        /// <summary>
        /// Returns a tuple list from a tuple view.
        /// </summary>
        /// <param name="tupleIndexer">The tuple indexer  used to select a view.</param>
        /// <param name="keyValue">A key value used for  match.</param>
        /// <typeparam name="TKey">The key type.</typeparam>
        /// <returns>
        /// A tuple list contains tuples that match a given key value. 
        /// </returns>
        /// <remarks>
        /// A tuple list is contains all tuples of the given type that meet a given criteria.
        /// </remarks>
        TupleLinkedList GetTupleList<TKey>(TupleIndexer<TTuple> tupleIndexer, TKey keyValue);

        /// <summary>
        /// Returns a tuple list from the 'all' tuple view.
        /// </summary>
        /// <param name="keyValue">A key value used for  match.</param>
        /// <typeparam name="TKey">The key type.</typeparam>
        /// <returns>
        /// A tuple list contains tuples that match a given key value. 
        /// </returns>
        /// <remarks>
        /// A tuple list is contains all tuples of the given type that meet a given criteria.
        /// </remarks>
        TupleLinkedList GetTupleList<TKey>(TKey keyValue);

        /// <summary>
        /// Returns a list of tuples from a tuple view that match the given key.
        /// </summary>
        /// <typeparam name="TKey">The key type.</typeparam>
        /// <param name="tupleView">The tuple view.</param>
        /// <param name="keyValue">The key value.</param>
        /// <returns>A linked list of tuples that match the key value.</returns>
        TupleLinkedList GetTupleList<TKey>(IDictionary tupleView, TKey keyValue);

        /// <summary>
        /// Returns a list of tuple lists that do not match a given key value.
        /// </summary>
        /// <param name="tupleIndexer">The tuple indexer used for comparison.</param>
        /// <param name="keyValue">A key value used for match.</param>
        /// <typeparam name="TKey">The key type.</typeparam>
        /// <returns>
        /// A list of tuple lists contains tuples that do not match a given key value.
        /// </returns>
        IList<TupleLinkedList> GetNotTupleLists<TKey>(TupleIndexer<TTuple> tupleIndexer, TKey keyValue) where TKey : IComparable;

        /// <summary>
        /// Registers an evaluator with the Tuple Relation.
        /// </summary>
        /// <param name="tupleIndexer">The tuple indexer to be registered.</param>
        /// <typeparam name="TKey">The tuple type.</typeparam>
        void RegisterIndexer<TKey>(TupleIndexer<TTuple> tupleIndexer);

        /// <summary>
        /// Registers an 'all' evaluator with the Tuple Relation.
        /// </summary>
        /// <param name="tupleIndexer">The 'All' tuple indexer to be registered.</param>
        void RegisterAllIndexer(TupleIndexer<TTuple> tupleIndexer);
    }
}
